ci: review CLI contract changes for docs impact - #178

Why

firecrawl-docs#1195 establishes the deterministic reconciliation baseline and initial drift report. This linked follow-up adds advisory semantic review for CLI contract changes that fixed extractors may not cover.

Summary

• Run an advisory Codex review when a relevant internal CLI pull request is opened, updated, reopened, or marked ready for review.
• Inspect commands, aliases, arguments, flags, defaults, validation, authentication, output formats, response handling, packaging, and release behavior.
• Compare the diff with current firecrawl-docs and return No documentation impact, Documentation gap, or Ambiguous.
• Upsert one PR comment with evidence, affected docs, the smallest next action, and an optional proposed docs patch.
• Keep analysis read-only and isolate comment permissions in a separate job. The agent cannot edit files, push branches, open PRs, or merge changes.

Safety and activation gates

• Depends on firecrawl-docs#1195 so the agent reads the merged reconciliation baseline from docs main.
• Requires a repository or organization OPENAI_API_KEY; without it, the job emits a notice and exits successfully.
• Runs only for non-draft, same-repository PRs. Fork PR coverage is intentionally deferred because Actions secrets are not exposed to untrusted forks.
• The review is advisory and is not a required check.

Test plan

• Parse the workflow as YAML.
• Syntax-check the embedded GitHub Script.
• Verify immutable action pins, path coverage, per-PR cancellation, fork/draft guards, read-only sandboxing, and isolated write permissions.
• Run git diff --check and confirm only the workflow and prompt are added.
• After the API key is configured, verify an internal CLI contract change receives one updated documentation-impact comment on successive pushes.

No CLI runtime behavior or documentation content changes in this PR.

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

Summary by cubic

Adds an advisory CI check that reviews CLI PRs for documentation impact and posts a single upserted comment with the outcome and evidence. No runtime or docs content changes.

• New Features
  • Add .github/workflows/docs-impact.yml and .github/prompts/docs-impact.md.
  • Triggers on open/sync/reopen/ready_for_review for same-repo, non-draft PRs touching CLI/release paths.
  • Runs openai/codex-action in read-only mode against the PR merge ref and firecrawl-docs main, returning No impact/Documentation gap/Ambiguous with evidence and smallest next action.
  • Publishes or updates one comment via a separate job with minimal write perms; the analysis cannot change code or docs.
  • Requires OPENAI_API_KEY; skipped if missing. Advisory only.

^{Written for commit 0c2304c. Summary will update on new commits.}